클로드 코드 완벽 가이드 — 23장 Claudia 딥다이브 학습 노트

출처: 클로드 코드 완벽 가이드 (코드팩토리 최지호) | 참고: https://github.com/codefactory-co

23장에서 다루는 내용

• Claudia(클로디아) 소개 — 클로드 코드에 GUI를 제공하는 오픈소스 데스크톱 앱
• 클로디아 설치하기 — Rust, Bun, OS별 의존성 설치 및 빌드 과정
• 에이전트 기능 — 반복 작업을 에이전트로 정의해 재사용하는 방법
• 세션 기능 — GUI에서 세션을 생성/관리/이어가기
• 사용량 확인 — Usage Dashboard로 토큰, 비용, 모델별 통계 분석

전체 흐름도

[클로디아란?]           [설치하기]              [핵심 기능 3가지]
    |                      |                       |
    v                      v                       v
+------------------+  +-------------------+  +------------------------+
| CLI이 부담스러운  |  | 1. Rust 설치      |  | 에이전트 기능           |
| 사용자를 위한     |  | 2. Bun 설치       |  | = 반복 작업 저장/실행   |
| GUI 솔루션        |  | 3. OS별 도구 설치  |  |                        |
|                  |  | 4. git clone      |  | 세션 기능               |
| Tauri 2 기반      |  | 5. bun install    |  | = 대화 생성/관리/이어감  |
| 데스크톱 앱       |  | 6. bun run tauri  |  |                        |
|                  |  |    build          |  | 사용량 확인             |
| 에이전트 저장     |  | 7. 번들 실행      |  | = 토큰/비용 통계 대시보드|
| 세션 관리         |  +-------------------+  +------------------------+
| 사용량 추적       |
+------------------+

핵심 키워드

23-1 클로디아 소개

한 줄 요약

클로디아는 CLI가 부담스러운 사용자도 클로드 코드를 그래픽 인터페이스에서 편하게 사용할 수 있게 해주는 Tauri 2 기반 오픈소스 데스크톱 앱이다.

쉬운 설명 (비유)

클로드 코드가 "문자로만 소통하는 비서"라면, 클로디아는 그 비서에게 "얼굴이 보이는 화상통화 앱"을 달아준 것이다. 기능은 똑같지만 버튼을 눌러서 지시할 수 있으니 훨씬 직관적이다.

클로디아가 해결하는 문제

❌ CLI만 사용할 때                    ✅ 클로디아를 사용할 때
터미널 명령어를 외워야 함             버튼 클릭으로 동작
세션 이어가기: claude -r 플래그       세션 리스트에서 Resume 클릭
에이전트 실행: 긴 명령어 입력         Agents 탭 → Run 클릭
사용량 확인: 별도 대시보드 접속       Usage Dashboard 탭 내장
CLAUDE.md 편집: 에디터로 직접 열기    CLAUDE.md 탭에서 바로 편집

클로디아의 핵심 특징

1. GUI 제공 — 명령어 없이 마우스/키보드로 클로드 코드 조작
2. 에이전트 관리 — 자주 쓰는 작업을 에이전트로 저장해두고 반복 실행
3. 세션 관리 — 기존 대화를 시각적으로 찾아서 이어가기
4. 사용량 추적 — 토큰, 비용, 모델별 통계를 한눈에 확인
5. 오픈소스 — 커뮤니티가 운영하는 무료 프로젝트 (github.com/getAsterisk/claudia)

핵심 체크포인트

• [ ] 클로디아는 클로드 코드를 대체하는 게 아니라 "위에 얹는 GUI"라는 점을 이해했는가?
• [ ] 실행 후 실제 작업은 클로드 코드가 수행하고, 클로디아는 GUI 역할만 한다는 점을 이해했는가?

23-2 클로디아 설치하기

한 줄 요약

Rust와 Bun을 먼저 설치한 뒤, 클로디아 저장소를 클론하고 bun install → bun run tauri build로 빌드하면 OS별 실행 파일이 생성된다.

쉬운 설명 (비유)

클로디아 설치는 "IKEA 가구 조립"과 비슷하다. 먼저 공구(Rust, Bun)를 준비하고, 부품(git clone)을 받은 뒤, 설명서대로 조립(build)하면 완성품이 나온다.

설치 과정 (단계별)

[1단계: Rust 설치]
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
# → Rust 1.70.0 이상 필요

[2단계: Bun 설치]
curl -fsSL https://bun.sh/install | bash
# → 최신 버전의 Bun 필요

[3단계: OS별 추가 도구]
# macOS:
xcode-select --install
brew install pkg-config     # 선택

# Windows:
Microsoft C++ Build Tools   # bit.ly/4ozXErb
WebView2                    # bit.ly/4oSrSWH

[4단계: 클론 & 이동]
git clone https://github.com/getAsterisk/claudia.git
cd claudia

[5단계: 의존성 설치]
bun install
# → 432 installs across 514 packages

[6단계: 빌드]
bun run tauri build

[7단계: 번들 실행]
# Linux:  src-tauri/target/release/bundle/linux
# macOS:  src-tauri/target/release/bundle/macos
# Windows: src-tauri/target/release/bundle/windows

OS별 필수 도구 비교

핵심 체크포인트

• [ ] Rust 1.70.0 이상이 설치되어 있는가?
• [ ] Bun이 정상적으로 설치되어 있는가?
• [ ] OS별 추가 도구(macOS: Xcode CLI, Windows: WebView2)가 준비되어 있는가?
• [ ] bun run tauri build 후 번들 폴더에 실행 파일이 생성되었는가?

23-3 클로디아 에이전트 기능

한 줄 요약

에이전트는 반복적인 클로드 코드 작업을 이름/아이콘/모델/시스템 프롬프트로 정의해두고, 버튼 하나로 언제든 재실행할 수 있는 기능이다.

쉬운 설명 (비유)

에이전트는 "매크로 버튼"과 같다. 매번 "Next.js 앱을 Tailwind + Tanstack으로 만들어줘"라고 길게 타이핑하는 대신, "NextJS Creator" 버튼 하나만 누르면 같은 작업이 시작된다.

에이전트 생성 과정

[Agents 버튼 클릭] → [Create Agent] → 설정 입력 → [Save] → [Run]

설정 항목:
┌──────────────────────────────────────────┐
│ ① Agent Name: "NextJS Creator"          │
│ ② Agent Icon: bot 아이콘 선택            │
│ ③ Model: Claude 4 Sonnet / Opus 선택     │
│ ④ System Prompt: 에이전트의 기본 지시사항  │
│    예) "NextJS 앱을 다음 기술스택으로 생성  │
│        - Tailwind CSS                    │
│        - Tanstack Table / Form           │
│        - Shadcn UI"                      │
│ ⑤ [Save] 버튼 클릭                       │
└──────────────────────────────────────────┘

에이전트 실행 과정

[Agents] → 에이전트 선택 → [Run] 클릭
                               |
                               v
┌──────────────────────────────────────┐
│ Execute: NextJS Creator              │
│                                      │
│ Project Path: /Users/.../claudia_test│
│ Model: Claude 4 Sonnet               │
│ Task: "쇼핑몰 사이트를 만들어줘"       │
│                                      │
│               [▶ Execute]             │
└──────────────────────────────────────┘
                               |
                               v
         클로드 코드가 작업을 실행
         (클로디아는 GUI 역할만)

실무 예제: 에이전트 활용 시나리오

핵심 체크포인트

• [ ] 에이전트 = System Prompt + 모델 + 이름/아이콘의 조합이라는 점을 이해했는가?
• [ ] Execute 후 실제 작업은 클로드 코드가 수행한다는 점을 이해했는가?
• [ ] Default Task와 실행 시 Task의 차이를 이해했는가? (Default Task는 미리 채워지는 기본값)

23-4 클로디아 세션 기능

한 줄 요약

세션 기능은 클로드 코드와의 대화를 GUI에서 시각적으로 생성, 관리, 이어가기(Resume)할 수 있게 해주며, CLI의 -r 플래그보다 훨씬 직관적이다.

쉬운 설명 (비유)

CLI에서 세션을 이어가는 것이 "전화번호를 외워서 다시 걸기"라면, 클로디아 세션은 "최근 통화 목록에서 터치해서 다시 걸기"와 같다.

세션 생성 및 관리 흐름

[+ 버튼] → [New Claude Code Session]
              |
              v
┌──────────────────────────────────────┐
│ Claude Code Session                  │
│ Project Directory: /Users/.../test   │
│                                      │
│ 모델 선택:                            │
│   ⦿ Claude 4 Sonnet (빠른 작업)      │
│   ○ Claude 4 Opus  (복잡한 작업)      │
│                                      │
│ Thinking Token 단계:                  │
│   Auto → Think → Think Hard          │
│   → Think Harder → Ultrathink        │
│                                      │
│ 프롬프트 입력 → [실행하기] 버튼        │
└──────────────────────────────────────┘

Thinking Token 5단계

세션 이어가기 (Resume)

❌ CLI 방식                          ✅ 클로디아 방식
claude -r                           CC Projects 화면에서
(어떤 세션인지 기억해야 함)            → 프로젝트 클릭
                                     → 세션 리스트 확인
                                     → [Resume] 클릭

• 활성 세션(Active Claude Sessions)은 상단에 "Running" 표시
• 프로젝트별로 모든 세션을 리스트로 확인 가능
• 각 세션의 첫 번째 메시지, 시작 시간, 세션 ID 표시

핵심 체크포인트

• [ ] 새 세션 생성 시 프로젝트 디렉터리와 모델을 선택해야 한다는 점을 이해했는가?
• [ ] Thinking Token 단계가 높을수록 더 많은 토큰을 소비한다는 점을 이해했는가?
• [ ] 프로젝트를 클릭하면 해당 프로젝트의 모든 세션 히스토리를 볼 수 있다는 점을 이해했는가?

23-5 클로디아 사용량 확인

한 줄 요약

Usage Dashboard에서 토큰 사용량, API 비용, 모델별/프로젝트별/세션별/시계열 통계를 한눈에 확인할 수 있다.

쉬운 설명 (비유)

클로디아의 Usage Dashboard는 "통신사 요금 조회 앱"과 같다. 이번 달 데이터를 얼마나 썼는지, 어떤 앱에서 많이 썼는지, 지난달과 비교해 얼마나 차이나는지 한눈에 보여준다.

확인 가능한 통계

┌──────────────────────────────────────────┐
│ Usage Dashboard                          │
│                                          │
│ 전체 사용량 요약                          │
│   - 총 토큰 사용량                        │
│   - API 비용 (달러)                       │
│                                          │
│ 모델별 통계                               │
│   - Claude 4 Sonnet: XX 토큰             │
│   - Claude 4 Opus: XX 토큰               │
│                                          │
│ 프로젝트별 통계                           │
│   - 프로젝트 A: XX 토큰                   │
│   - 프로젝트 B: XX 토큰                   │
│                                          │
│ 세션별 통계                               │
│   - 세션 1: XX 토큰                       │
│                                          │
│ 시계열 통계                               │
│   - 이번 달 vs 지난 달 비교               │
└──────────────────────────────────────────┘

실무 활용: 비용 최적화 전략

핵심 체크포인트

• [ ] Usage Dashboard에서 모델별, 프로젝트별, 세션별, 시계열 4가지 관점의 통계를 확인할 수 있다는 점을 이해했는가?
• [ ] API를 사용하는 경우 비용을 추적할 수 있다는 점을 이해했는가?

선수 지식 체크리스트

연습문제

연습문제 1: 에이전트 설계

자신이 자주 하는 반복 작업 3가지를 에이전트로 설계해보세요. 각 에이전트의 이름, 모델(Sonnet/Opus), System Prompt를 작성하세요.

에이전트 1: "README Generator"
- 모델: Claude 4 Sonnet
- System Prompt: "프로젝트 구조를 분석하고 README.md를 생성해줘.
  설치 방법, 사용 방법, API 문서를 포함해줘."

에이전트 2: "DB Schema Designer"
- 모델: Claude 4 Opus
- System Prompt: "요구사항을 분석하고 PostgreSQL 스키마를 설계해줘.
  ERD, 마이그레이션 파일, 시드 데이터를 포함해줘."

에이전트 3: "Performance Optimizer"
- 모델: Claude 4 Sonnet
- System Prompt: "코드의 성능 병목을 찾고 최적화 방안을 제시해줘.
  프로파일링 결과와 개선 전후 비교를 포함해줘."

연습문제 2: 설치 트러블슈팅

클로디아 설치 시 bun run tauri build에서 오류가 발생했다면, 가장 먼저 확인해야 할 3가지는 무엇인가?

연습문제 3: CLI vs 클로디아 비교

다음 작업을 CLI와 클로디아로 각각 수행하는 방법을 비교하세요: (1) 이전 세션 이어가기 (2) 에이전트 실행 (3) 사용량 확인

부록 A — 용어사전

부록 B — 비교표

CLI vs 클로디아 기능 비교

Thinking Token 단계별 비교

부록 C — 참고자료